Mac Format 1996 April

home *** CD-ROM | disk | FTP | other *** search

/ Mac Format 1996 April / MacFormat CD Edition MF36 (April 1996).iso / Shareware City / Developers / Tools Plus - GUI⁄Event libs / Tools Plus 2.6.1a Evaluat'n Kit / Tools Plus 2.6.1a / User Manual / 23-Completing Your Application < prev next >

Wrap

INI File | 1995-04-01 | 28KB | 402 lines

[Display using Monaco 9] 23 Completing Your Application ``````````````````````````````` This section details the final steps that you must take to produce a stand-alone, double-clickable application. The requirements for an application using Tools Plus libraries are nearly identical to those of ordinary Macintosh applications, except that the SIZE resource has some very specific needs. It is assumed that by the time you address these concerns, you have already written and debugged an application within your development environment and that you are ready to make it a stand-alone application. All the work encompassed in this section requires that you use a resource editor such as Apple’s ResEdit to create and/or modify resources. The Symantec and Metrowerks development environments allow you to use a resource file as part of your project. That resource file is automatically merged into your compiled code when you build your project. Therefore we recommend you create and save these resources in a separate resource file and allow your development environment to merge them with your application (instead of manually adding them to your compiled application). Completing your application involves making some decisions, then creating the appropriate resources. The table below summarizes the various tasks and their significance to your final application. ===============================+======================================== Task (section in this chapter) | Significance to your application ===============================+======================================== Application Icons | Defines the icons that are displayed by File Types, Creators, and the | the Finder for your application and the Application Signature | files it creates. Bundle (BNDL resource) | -------------------------------+---------------------------------------- Version (vers resource) | For displaying a version number in your | application’s “Get Info” box. An | application description can also be | displayed. (Optional) -------------------------------+---------------------------------------- mstr resource | Remapping of the File menu’s “Quit” | item and the File menu’s “Open…” item | to another menu and/or menu item. | The “Quit” command is automatically | invoked when your application is | running and the user selects the | Special menu’s Restart or Shut Down | commands. | The “Open…” command is automatically | invoked when your application is | running and the user double-clicks | (opens) a document created by your | application. | If your application does not have | the “Open…” or “Quit” items in a “File” | menu, and your application will [i] run | on Macs with System 5 or 6, or [ii] not | process high-level events, you need to | add mstr resources. (Optional) -------------------------------+---------------------------------------- SIZE resource | Defines your application’s behavior and | memory requirements in a multi- | tasking environment. Needed for | MultiFinder and System 7. -------------------------------+---------------------------------------- Application’s Icons ``````````````````` The Macintosh’s Finder displays an application and its related files as icons. In order for the Finder to do this, it needs to know what each icon looks like. Without this information, your application will have the “generic application” icon (diamond with a hand holding a pen) and its related files will have the “generic document” icon (blank page with corner folded down). At the very least, you will need to create a large (32x32 bit) black and white icon (ICN#) for your application, and one for each type of document it creates. You should also consider creating equivalent small (16x16 bit) black and white icons (ics#), because the Finder displays these miniatures when a disk’s or folder’s view is set to “small icon,” or when System 7 displays lists with icons. System 7 can display your application’s icons in color, so you can optionally include color icons as equivalents for the black and white ones. The icl8 and icl4 icon types are large icons using 8 bits (256 colors) and 4 bits (16 colors) respectively. Small color icons can also be created as ics8 and ics4 type icons. Later, the “bundle” describes how to integrate the icon resources into your finished application. Icon Family ``````````` When a specific icon ID number is shared by two or more icon types, those related icons are called an “icon family.” The icon family with an ID of 128 is usually the icon that depicts your application. Your application’s document icons would likely be numbered 129 and up. When you create icons, remember to use ID numbers 128 or higher. The rest are reserved numbers. Note: When creating icl8 and ics8 icons with ResEdit, you have a choice of two color palettes: “Apple icon colors” or “Standard 256 colors.” Use the Apple icon colors, since they will guarantee that your icon can be selected (darkened) properly. File Types, Creators, and the Application Signature ``````````````````````````````````````````````````` On the Macintosh, all files (including application, desk accessories, documents, etc.) have a file type and a creator code. Both of these items are always four characters long, allowing any visible or invisible characters and spaces. The file type tells the Macintosh what the file contains. Your application will always have a file type of ‘APPL.’ You can define your own file types for the documents created by your application if they don’t fit into any of the existing general types as follows: APPL Launchable application DFIL File for sorting DAs DRVR Driver FFIL File for sorting fonts INIT System extension PICT QuickDraw picture PRER Printer driver RDEV Chooser extension TEXT Stream of ASCII characters adev Network extension appe Background-only application cdev Control panel edtp Edition for sharing graphics edts Edition for sharing sound edtt Edition for sharing text ffil Font ifil Script system resources kfil Keyboard layout pref Preferences file qery Query document (databases) scri System extension for scripting sfil Sound tfil TrueType font ttro TeachText read-only file zsys A system file Later, the “bundle” describes how to integrate file type(s) into your finished application. Signature (the Creator code) ```````````````````````````` Each application must have a unique, four character signature. A signature is often called a creator code because it answers the question “who created me” for every document on a Macintosh (an application is considered to be its own creator). Your application’s signature will be used as the creator code for all the documents it creates. The Finder makes an association between each application and its related documents by using the application’s signature. When a document is opened by the Finder, it knows which application created the file and automatically launches that application. Notice that some file types can be opened by several applications. If you double-click a ‘TEXT’ file, it will be opened by the application that launched it (because the Finder recognizes the creator for the file is identical to the parent application’s signature). However, just about any word processor can open a ‘TEXT’. In THINK Pascal, you set your application’s type and creator by using the Project menu’s “Set project Type” command. Later, the “bundle” describes how to integrate the signature into your finished application. Note: Apple reserves the use of all file types and signatures (creator codes) whose names contain only lowercase letters, and those that contain only non-alphabetic characters. Your file types and signatures must contain at least one uppercase letter. Since the system software never displays the file type or signature to users, these codes don’t have to be meaningful to anyone but you. All file types and signatures must be registered with Apple to guarantee uniqueness and prevent conflicts between applications. Warning: When deciding upon a signature for your application, be careful to avoid signatures that are identical to any existing resource type, such as ‘ICON’ or ‘STR ’. An owner resource must be created with a type that matches your application’s signature, and if it coincides with existing resources types, conflicts may arise. For a comprehensive list of resource codes, please refer to the ResEdit Reference manual, or contact Apple. Bundle `````` The BNDL resource, which is simply called the “bundle,” is used to “bundle up” several related resources that are needed to define the association between your application, its documents, and the icons displayed by the Finder. If you use ResEdit to create the BNDL resource, you will be presented with a template that lets you create and maintain the BNDL resource. Enter the four character signature you have selected for your application. Next, use the Resource menu’s “Create New File Type” command to create a new line. Enter the file type. Note that the first line should have a type of ‘APPL’ (application). Double-click its “Finder Icons” section and you will be presented with a list of icons that you created earlier in the “Application Icons” section of this chapter. Select the icon you want to use to represent the specified file type. Repeat this for each file type that is supported by your application. The last thing you must do to complete the bundle is to set the “bundle bit.” The bundle bit tells the Finder that your application has a bundle present. In THINK Pascal, you set the bundle bit by using the Project menu’s “Set project Type” command, then building your application. The bundle bit is set automatically in THINK C/C++ and Metrowerks compilers. When creating the BNDL resource, ResEdit automatically creates several other supporting resources. One FREF resource (Finder REFerence) is created for each file type. An “Owner Resource” is also created (ID=0). Its resource type matches your application’s signature. The owner resource is essentially a string resource that lets you enter a comment that is displayed as version information in the Finder’s “Get Info” box (providing you don’t create ‘vers’ resources). Note: If you change your application’s icons, you will have to rebuild the desk top file to force the Finder to use your new icons. To rebuild the desk top, restart your Macintosh while holding the option and command keys down, and continue to hold them until you see a dialog that asks you if you want to rebuild your desk top. Click the OK button to start rebuilding. A similar problem sometimes occurs when an application is copied to a disk using an installer or decompression program. These kinds of programs may not have the intelligence to update the desk top file like the Macintosh’s Finder does. Version ``````` Your application can display some descriptive information in the Finder’s “Get Info” box by having ‘vers’ resources. The two vers resources you can include in your applications are: ID=1 Application version number (i.e. 2.5, ©1994 - Water’s Edge Software) ID=2 Application info displayed beneath the file name (i.e., Tools Plus Library (1 of 3) ) By using vers resources, any file can bear version information, including documents created by your application. mstr Resources `````````````` This section describes how System 5 and 6’s MultiFinder and System 7 automatically interact with your application’s menus if your application does not support high-level events (also called Apple Events). You should set the appropriate bit in your application’s ‘SIZE’ resource to indicate if it supports Apple Events or not. Both MultiFinder (running under System 5 or 6) and System 7 can automatically interact with your application through its menus. If your application is running while the user double-clicks (or select-opens) one of your application’s documents from the Finder, the affected document is automatically opened by your application. Also, if the user selects the Special menu’s Restart or Shut Down command while your application is running, it is instructed to quit. In both these cases, the system simulates the selection of a menu item. Typically applications have a File menu with an item named “Open…” (including the ellipsis, the Option-; character), and the last item named “Quit”. In the case of opening a document, PollSystem returns a doMenu event to your application indicating that the File menu’s “Open…” command was selected, in which case your application would do whatever is appropriate, like display an SFGetFile dialog to let the user choose which file to open. The system fools your application into thinking that the double-clicked file was selected from an SFGetFile dialog (which is not actually displayed). When the user selects Restart or Shut Down, PollSystem returns a doMenu event to your application indicating that the File menu’s “Quit” command was selected, in which case your application would do whatever is appropriate, such as asking if open documents should be saved before quitting. If your application does not [1] open files by using the File menu’s “Open…” command, or [2] quit by using the File menu’s “Quit” command, these functions can be remapped to other menu items by including ‘mstr’ resources in your application. Each mstr resource is a Pascal string (byte-0 is the length byte) that tells the Macintosh which menu and menu item to use in place of the standard ones: mstr ID=100 Name of the menu containing the equivalent of the “Quit” command mstr ID=101 Name of the menu item that is the equivalent of the “Quit” command mstr ID=102 Name of the menu containing the equivalent of the “Open…” command mstr ID=103 Name of the menu item that is the equivalent of the “Open…” command SIZE Resource ````````````` If your application is going to run under MultiFinder or System 7, it needs a SIZE resource. ResEdit has a resource template for the SIZE resource, which lets you set various values in the resource to specify how your application behaves in a multi-tasking environment. You will create a single resource with an ID of -1, but be aware that the Macintosh may clone (make a duplicate with a possible minor variation) your SIZE resource in your stand-alone application under certain conditions. This is described later. The SIZE resource is comprised of sixteen bits that can be set to a value of 0 or 1, and two long integers. Tools Plus requires that some of these items be set to a specific value while others depend upon how you want your application to behave. The table below details the SIZE resource. Compulsory Setting \ / Recommended Setting \ / SIZE Template’s Field Name | | | Comments ===========================+=+=+======================================== Save screen (obsolete) |0|0| (obsolete) ---------------------------+-+-+---------------------------------------- Accept suspend events |1|1| 0 = doSuspend and doResume events are | | | not reported to your application. | | | 1 = Your application receives a | | | doSuspend event prior to being | | | suspended, and a doResume event | | | immediately after being activated. ---------------------------+-+-+---------------------------------------- |0|0| (obsolete) ---------------------------+-+-+---------------------------------------- Can background | |1| 0 = When your application is suspended, | | | it receives no processing time | | | 1 = When your application is suspended, | | | it receives processing time in the | | | way of doNothing events. | | | If “Accept suspend events” is set to 0, | | | this item must be set to 1. ---------------------------+-+-+---------------------------------------- Does activate on FG switch |1|1| 0 = The Macintosh’s operating system | | | takes care of activating and | | | deactivating a window when the | | | application is suspended or | | | resumed. | | | 1 = Your application takes care of | | | activating or deactivating its | | | windows in response to a doSuspend | | | or doResume event (automatic in | | | Tools Plus). | | | This item must have the same setting as | | | “Accept suspend events.” ---------------------------+-+-+---------------------------------------- Only background |0|0| 0 = Your application is a regular | | | application. | | | 1 = Your application runs only in the | | | background. Usually, this is | | | because it doesn’t have a user | | | interface and cannot run in the | | | foreground. ---------------------------+-+-+---------------------------------------- Get front clicks | |0| 0 = Your application does not receive | | | the mouse-down used to activate it | | | after being suspended. Most | | | applications work this way. | | | 1 = The mouse-down that activates your | | | application is applied to your | | | application. This may mean that a | | | button is selected, drawing begins, | | | or an insertion point is set. The | | | Finder works in this manner. ---------------------------+-+-+---------------------------------------- Accept app died events | |0| 0 = ApplicationDied events are not (debuggers) | | | generated | | | 1 = Your application is notified (via | | | an ApplicationDied event) when an | | | application or process launched by | | | your application has terminated or | | | has crashed. Read about System 7’s | | | Process Manager for more details. ---------------------------+-+-+---------------------------------------- 32 bit compatible | |1| 0 = Your application is not 32-bit | | | compatible | | | 1 = Your application can be run with | | | the 32-bit Memory Manager. | | | Modern Mac compiler’s generate 32-bit | | | compatible code, so your app is 32-bit | | | clean providing you do not modify your | | | application’s addressing. ---------------------------+-+-+---------------------------------------- High level event aware | |0| 0 = No high-level events are received | | | or sent by your application | | | 1 = Your application can receive and | | | send high-level events (System 7) | | | If this item is set to 0, MultiFinder | | | and System 7 will automatically | | | interact with your application’s menus. | | | See the “Menus” chapter for details. ---------------------------+-+-+---------------------------------------- Local and remote high | |0| 0 = Your application cannot be level events | | | accessed by applications running on | | | other computers on a network. | | | 1 = Your application is accessible by | | | applications running on other | | | computers on a network, and it can | | | receive high-level events across a | | | network (System 7). ---------------------------+-+-+---------------------------------------- Stationery aware | |0| 0 = If the user opens a stationary | | | document (System 7), the Finder | | | makes a copy of the file and asks | | | the user to name the copy. | | | 1 = Your application knows how to work | | | with stationery documents | | | (System 7) ---------------------------+-+-+---------------------------------------- Use text edit services | |0| 0 = Your application does not use | | | inline TextEdit services | | | 1 = Your application uses inline | | | TextEdit services (System 7). | | | Tools Plus’s editing fields don’t use | | | inline TextEdit services. Set this | | | item to 1 only if you have designed | | | your own editing fields that use these | | | services. ---------------------------+-+-+---------------------------------------- Reserved bit |0|0| (reserved for future use) ---------------------------+-+-+---------------------------------------- Reserved bit |0|0| (reserved for future use) ---------------------------+-+-+---------------------------------------- Reserved bit |0|0| (reserved for future use) ---------------------------+-+-+---------------------------------------- Size | | | The memory size at which your | | | application can run most efficiently. | | | When your application is launched, the | | | Operating System tries to secure this | | | amount of memory. ---------------------------+-+-+---------------------------------------- Min size | | | The memory limit below which your | | | application will not run. ---------------------------+-+-+---------------------------------------- Cloned SIZE resources ````````````````````` Although you need to create only one SIZE resource (ID=-1), the Macintosh may make clones of it when the user makes changes in the Finder’s “Get Info” box. When the user makes changes in the “Get Info” box, the Macintosh clones (makes a copy of the SIZE resource with ID=-1) and lets the user makes changes to the “Size” and “Min size” fields of the clone. You only need to be concerned with this if you want to preset your application’s memory requirements to something other than the recommended limits defined by your original SIZE resource. The table below describes the contents of the “Size” and “Min size” fields for the original SIZE resource, as well as any clones that may be created by the Macintosh. ===========+====+=========+================+============================ System File|SIZE| Field’s | Title in | Version | ID | Name | “Get Info” box | Contents ===========+====+=========+================+============================ 5 to 7.0.x | -1 |Size |Application | Memory required for optimum | | |memory size | performance | +---------+----------------+---------------------------- | |Min size |Suggested memory| Memory limit below which | | |size | your application won’t run +----+---------+----------------+---------------------------- | 0 |Size |Application | User’s setting | | |memory size | | +---------+----------------+---------------------------- | |Min size |Suggested memory| Memory limit below which | | |size | your application won’t run | | | | (same as ID=-1) -----------+----+---------+----------------+---------------------------- 7.1 or | -1 |Size |Suggested size | Memory required for optimum higher | | | | performance | +---------+----------------+---------------------------- | |Min size |(not displayed) | Memory limit below which | | | | your application won’t run +----+---------+----------------+---------------------------- | 0 |Size |Preferred size | User’s preferred memory | | | | allowance | +---------+----------------+---------------------------- | |Min size |(not displayed) | Memory limit below which | | | | your application won’t run | | | | (same as ID=-1) +----+---------+----------------+---------------------------- | 1 |Size |(not displayed) | User’s preferred memory | | | | allowance | | | | (same as ID=0) | +---------+----------------+---------------------------- | |Min size |Minimum size | User’s minimum memory | | | | allowance below which the | | | | application won’t run. -----------+----+---------+----------------+----------------------------